Skip to main content

Data Request Payload

This document provides a detailed explanation of the payload object model used in data requests, outlining its structure, components, and examples.

Overview​

The payload object contains the core details of the data request, specifying the credentials being requested and their associated attributes. It ensures that the request is well-defined and includes the necessary information for users to respond effectively.

Structure of the payload Object​

Fields​

  1. name

    • Type: string
    • Description: A descriptive name for the data request. This helps users understand the purpose of the request.

  2. credentials

    • Type: array
    • Description: An array of credential objects, each specifying the format, name, restrictions, and attributes required for the data request.

Credential Object Structure​

Each credential object contains the following fields:

  1. format

    • Type: string
    • Description: The format of the credential being requested (e.g., w3c, sdjwt).
    • Default: w3c

  2. name

    • Type: string
    • Description: The name of the credential being requested. This provides context for the type of credential.

  3. restrictions

    • Type: object (Optional)
    • Description: Specifies constraints for the credential, such as the schema or issuer. Restrictions ensure that the requested credentials adhere to predefined standards.
    • Reference: Read more about the restrictions object here.

  4. attributes

    • Type: array
    • Description: An array of attribute objects specifying the required attributes within the credential.

Attributes Object Structure​

Each attribute object includes the following fields:

  1. name

    • Type: string
    • Description: The name of the attribute being requested (e.g., email, license_number).
    • Required: Yes

  2. isRequired

    • Type: boolean (Optional)
    • Description: Indicates whether the attribute is mandatory for completing the data request. Defaults to false if not specified.

Example Payload​

Below is an example of a payload object:

{
  "payload": {
    "name": "Provide email to complete flow.",
    "credentials": [
      {
        "format": "w3c",
        "name": "W3C Verified Email",
        "restrictions": {
          "schemaId": "https://137.dev-one37.id/bc/public/schemas/com.one37id.email/1.0",
          "attributes": [
            {
              "key": "_namespace",
              "value": "personal.contact.verifiedemail"
            }
          ]
        },
        "attributes": [
          {
            "name": "email",
            "isRequired": true
          }
        ]
      }
    ]
  }
}

Explanation​

  1. name: Describes the purpose of the data request as "Provide email to complete flow."
  2. credentials: Contains an array with one credential:
    • format: Specifies the credential format as w3c.
    • name: Indicates the credential name as "W3C Verified Email."
    • restrictions:
      • Defines the schema ID for the credential.
      • Specifies additional constraints using attributes, such as _namespace with the value personal.contact.verifiedemail.
    • attributes:
      • Includes one attribute, email, which is marked as required (isRequired: true).

Summary​

The payload object is a critical component of data requests, defining the credentials and attributes required from users. By utilizing fields like name, credentials, and their nested structures (format, restrictions, attributes), it provides a flexible and detailed way to specify the exact data needed.

For more details on the restrictions model, refer to the Restriction Model Documentation.

X

Graph View